Introducing MapLibre GL Teritorio Cluster

👉 Live demo: teritorio.github.io/maplibre-gl-teritorio-cluster

What it does

MapLibre GL Teritorio Cluster is a plugin that extends MapLibre GL JS with a new layer type dedicated to clustering.
It manages clustering logic and state transitions internally.

It provides three key states out of the box:

• Cluster Marker – Displays aggregated markers and their feature counts.
• Unfolded Cluster – A flattened, aggregated cluster providing direct access to cluster content without requiring any zoom or ungrouping actions, acting as unclustered markers.
• Unclustered Marker – Represents single features.

Built for customization

You can customize every rendering part with:

new TeritorioCluster('cluster-layer', 'points', {
  clusterRender: () => { /* custom HTML/CSS for cluster */ },
  unfoldedClusterRender: () => { /* custom HTML/CSS for unfolded cluster */ },
  markerRender: () => { /* custom HTML/CSS for marker */ },
  pinMarkerRender: () => { /* custom HTML/CSS for pin marker */ },
})

Listen events on clusters or markers (feature-click).

Unfolded cluster layouts are customizable:

• Smart (default):

• Circle

• Grid

• Hexagonal

Quick Start

Install via Yarn or use it directly from a CDN:

yarn add @teritorio/maplibre-gl-teritorio-cluster

<script type="module" src="https://unpkg.com/@teritorio/maplibre-gl-teritorio-cluster/dist/maplibre-gl-teritorio-cluster.js"></script>

Make sure your GeoJSON source uses:

clusterMaxZoom: 22 // Required to enable full control at max zoom

What it includes

• Includes built-in helpers (buildCss) for simpler styling
• Includes built-in layouts (circle, hexagonal, grid, smart) for simpler styling
• Supports custom layouts and events
• Easy to integrate in React, Vue, or vanilla JS

Open Source, Open to Contribution

The project is open source under MIT license, maintained by Teritorio.

We’d love feedback, ideas, and contributions from the MapLibre community.

📦 GitHub: github.com/teritorio/maplibre-gl-teritorio-cluster